Quarto 入门教程 (3)：细节设置

点击下方公众号，回复资料分享，收获惊喜

简介

本文是《手把手教你使用 Quarto 构建文档》第三期，前两期分别介绍了：

1. 第一期（可点击） 介绍了Quarto 构建文档的原理；可创建的文档类型；对应的参考资源分享。

2. 第二期（可点击）介绍了如何使用 Quarto，并编译出文档（PDF，MS Word，html）等。

本期将介绍 Quarto 细节设置部分（知识点很多！可收藏），目录如下：

• 简介

• 代码框展示

• 隐藏代码

• 折叠代码

• 图形设置

• 交叉引用

• 多图排版

• 数据框

• 内联代码

• 缓存

代码框展示

根据第二期的内容，读者可以编译出各种格式的文档，默认情况下 HTML 输出结果如下：

隐藏代码

如果读者需要隐藏所有代码，而只展示代码结果，可以通过 echo: false 实现。

---
title: "Quarto Computations"
execute:
  echo: false
---

运行后的结果如下：

如果需要指定展示某个代码，可以在该代码块中加入 echo: true。

指定展示某个代码

注意：这里的选项设置和 R markdown 非常相似，具体见Rmarkdown教程（3）。例如：eval、include、prompt、comment、results 和错误信息选项warning、error、message 等。有关其他 Knitr 单元选项详细信息可见这^[1]。

折叠代码

如果读者想折叠代码而不是隐藏所有代码，可使用 code-fold。

---
title: "Quarto Computations"
format:
  html:
    code-fold: true
---

code-fold：代码折叠

还可以提供对代码折叠的全局控制，尝试添加 code-tools: 。

---
title: "Quarto Computations"
format:
  html:
    code-fold: true
    code-tools: true
---

图形设置

可以通过设置 fig-width 和 fig-height 来改变宽高比；fig-cap 修改标签以进行交叉引用；fig-alt 添加替代文本。

交叉引用

使用以下代码设置图片展示效，并使用 @fig-scatterplot 进行交叉引用。

#| label: fig-scatterplot
#| fig-cap: "City and highway mileage for 38 popular models of cars."
#| fig-alt: "Scatterplot of city vs. highway mileage for cars, where points are colored by the number of cylinders. The plot displays a positive, linear, and strong relationship between city and highway mileage, and mileage increases as the number of cylinders decreases."
#| fig-width: 6
#| fig-height: 3.5

多图排版

如果读者想并排两个图形，并为每个图添加描述性小标题。可以配合 使用 layout-ncol: 2、fig-cap 和 fig-subcap。读者可以使用 @fig-mpg 引用母图。@fig-mpg-1 和 @fig-mpg-2 引用子图。

#| label: fig-mpg
#| fig-cap: "City and highway mileage for 38 popular models of cars."
#| fig-subcap:
#|   - "Color by number of cylinders"
#|   - "Color by engine displacement, in liters"
#| layout-ncol: 2
#| column: page

ggplot(mpg, aes(x = hwy, y = cty, color = cyl)) +
  geom_point(alpha = 0.5, size = 2) +
  scale_color_viridis_c() +
  theme_minimal()

ggplot(mpg, aes(x = hwy, y = cty, color = displ)) +
  geom_point(alpha = 0.5, size = 2) +
  scale_color_viridis_c(option = "E") +
  theme_minimal()

数据框

可以使用 df-print 文档选项控制默认情况下打印数据框的方式。可用选项包括：

选项	描述
default	将默认的S3方法用于数据框架。
kable	使用 `knitr::kable()`[2]函数生成 Markdown 表格。
tibble	使用 `tibble`[3] 包的纯文本表。
paged	使用 `rmarkdown::paged_table()`[4] 实现带有行和列溢出分页的 HTML 表格。

例如，指定对数据框进行分页打印：

---
title: "Document"
format: 
   html:
     df-print: paged
---

内联代码

要在 markdown 中包含可执行表达式，请将表达式括在'r'中。例如，我们可以使用内联代码来说明数据中的观察数量：

我们数据中包含了 `r nrow(mpg)` 个数据。

缓存

如果文档包含计算时间过长的代码块，读者可能需要缓存这些代码块的结果。可以在 YAML 执行选项中设置 cache: true 。

execute:
  cache: true

缓存所有代码块可能不合适，也可以在特定的代码块中设置：

#| cache: true

渲染文档时，将看到在工作目录中创建了一个新文件夹，其名称与文档相同，后缀为 _cache。该文件夹包含缓存的结果。如果读者对该方面感兴趣，可见详细缓存细节^[5]。

参考资料

[1]

这: https://quarto.org/docs/reference/cells/cells-knitr.html

[2]

knitr::kable(): https://bookdown.org/yihui/rmarkdown-cookbook/kable.html

[3]

tibble: https://tibble.tidyverse.org/

[4]

rmarkdown::paged_table(): https://pkgs.rstudio.com/rmarkdown/reference/paged_table.html

[5]

缓存细节: https://quarto.org/docs/projects/code-execution.html#cache

相关推荐